package com.zm.blog.utils.storage;

import com.zm.blog.vo.FileVO;

import java.util.List;

/**
 * 统一存储服务接口
 * 定义文件存储的核心操作，支持多种存储实现（本地、OSS、云存储等）
 */
public interface StoreService {

    /**
     * 批量删除文件
     *
     * 注意：实际实现应考虑事务补偿机制
     *
     * @param files 待删除文件标识列表（可以是路径、URL或存储ID）
     * @throws StoreOperationException 删除失败时抛出
     */
    void deleteFile(List<String> files);

    /**
     * 保存文件
     *
     * 典型流程：
     * 1. 文件唯一性校验
     * 2. 文件内容校验（大小、类型）
     * 3. 写入存储系统
     * 4. 返回带访问路径的文件信息
     *
     * @param fileVO 文件值对象（包含文件名、内容、元数据等）
     * @return 保存后的文件信息（包含存储路径、访问URL等）
     * @throws StoreOperationException 存储失败时抛出
     */
    FileVO saveFile(FileVO fileVO);

    /**
     * 获取存储服务名称
     *
     * 用途：
     * - 多存储源切换
     * - 日志标识
     * - 监控统计
     *
     * @return 存储服务唯一标识（如："local"、"aliyun-oss"）
     */
    String getStoreName();

    // === 可选扩展 ===
    // 根据业务需求可扩展以下方法

    /**
     * 获取文件访问URL（可选扩展）
     * @param fileId 文件唯一标识
     * @param expireSeconds URL有效期（秒），0表示永久
     * @return 带签名的访问URL
     */
    default String generateAccessUrl(String fileId, long expireSeconds) {
        throw new UnsupportedOperationException("未实现访问URL生成功能");
    }

    /**
     * 文件是否存在（可选扩展）
     * @param fileId 文件唯一标识
     * @return 存在状态
     */
    default boolean fileExists(String fileId) {
        throw new UnsupportedOperationException("未实现文件存在性检查");
    }

}
